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David Boreham August 9, 1999 

What is a Role ? 

DS5.0 Roles embody a new comprehensive entry grouping mechanism, similar to the existing Directory 
Server group concept. Roles address many of the known shortcomings present in static and dynamic 
groups. Roles unify all entry grouping functions within one mechanism that is both easy to use and 
understand. Terminology primer: each role has members, which are the entries said to possess the role. 
In order to achieve reasonable implementation efficiency and to support certain important management 
functions, two different varieties of roles are envisaged. These are termed the simple and complex role 
types. 

How are Roles Defined? 

Each and every role is defined by its own role definition entry. A role is uniquely identified by the 
distinguished name of its defining entry. Role definition entries are LDAP subentries and so inherit the 
subentry mechanism for scope of application to a DIT subtree. LDAP Subentries are defined in 

That each and every role is defined by an entry stored in the DIT is of fundamental importance. Any 
client with appropriate access rights can discover, identify and examine any role definition. Any client 
with appropriate access rights can add a new role definition and modify existing role definitions. Role 
definitions may be replicated in a distributed environment. 

Role Operations 

Given arbitrary roles and entries, the following operations are useful to clients: 

1 . Enumerate the members of a role. (Answer the question "which entries have this role ?"). It's also 
useful to be able to resolve this query in a reasonable time (significantly less than the time to find 
the members by brute force examination of all the entries). It's also useful to be able to retrieve the 
entries in a paged or browsing fashion, using the existing LDAP VLV mechanism. 

2. Determine whether a given entry possesses a particular role. It's useful to be able to do this more 
efficiently than by determining all the roles possessed by the entry and then checking whether the 
target role is among that set of roles. 

3. Enumerate all the roles possessed by a given entry. 

4. Assign a particular role to a given entry. 

5. Revoke a particular role from a given entry. 

Tell us about the two Kinds of Role 

Certainly. Imagine that all roles were treated similarly. A role definition could be as complex as required 
or desired. An example of a complex role would be a nested role whose component roles included filters 
using custom matching rules and attribute syntax. Now consider the set of operations we desire to 
support for roles, listed above: 
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1 . Membership enumeration: to enumerate the members, a client would need to separately enumerate 
the component roles, by submitting search operations to the server. The results would need to be 
aggregated by the client, eliminating any duplicates. While this is possible, it's onerous. 

2. Determine whether a given entry possesses this role: this is really hard for a client to do. A brute 
force method would be terribly inefficient. Some associative indexing scheme could potentially 
help but seems hard to implement well. 

3. Enumerate all the roles possessed by a given entry: this is harder than (2). 

4. Assign this role to a given entry: This is really hard, requiring semantic knowledge of the role 
definition. 

5. Just as hard as (4). 

So, we have asserted that for a complex role such as the example used above, it is hard or very hard to 
implement any of the five desirable role operations. Therefore we define a role type with deliberately 
limited flexibility, called a simple role, which does allow all five of the desirable role operations to be 
implemented easily and efficiently. Any role that is not a simple role is by definition a complex role. 

A simple role has the following properties: 

1 . It's easy and efficient to enumerate its membership. This enumeration can be done using VLV 
controls, allowing better scaling and user experience. 

2. It's easy and efficient to test an entry for possession of a particular role. 

3. It's easy and efficient to enumerate the simple roles a particular entry possesses. 

4. It's obvious by inspection of the role definition how to assign a simple role to a given entry. 

5. It's obvious by inspection of the role definition how to revoke a simple role from a given entry. 

Roles which are not simple are deemed complex, with the implication that one or more (perhaps all) of 
the five operations are hard or very hard. Clients and management agents can easily determine whether a 
given role is of the simple or complex kind, allowing UI to act appropriately. Various server features 
which use roles will not be supported, or supported in a limited or inefficient way, when the target role 
is complex. Internal to the server, it is also possible to deliver notification to subsystems when entries 
move in and out of simple group membership. This can be used to keep metadata cached for 
performance reasons coherent with the DIT contents. 



Roles Compared to Legacy Grouping Mechanisms 
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Role Definitions, Take Two 

Having covered the difference between simple and complex roles, let's return to the details of role 
definition schema: 

There are two "abstract" object classes to distinguish between simple and complex roles: nsSimpleRole 
and nsComplexRole. 

Currently there is only one variety of simple role: the managed role with object class nsManagedRole. 
Membership of a managed role is conferred upon an entry by adding the role's DN to the entry's 
nsRoleDN attrbitute. Example of a managed role definition: 

dn : cn=managerrole, dc=dom, dc=ain 
objectclass: top 
objectclass: LDAPsubentry 
objectclass: nsRole 
objectclass: nsSimpleRole 
objectclass: nsManagedRole 
cn: managgerrole 

description: Manager Role within the Company 
Example of an entry with this role: 

dn: uid=pointyhair, ou=people, dc=dom, detain 

objectclass: top 

objectclass : person 

objectclass: inetorgperson 

uid: pointyhair 

gn : pointy 
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sn: hair 

nsRoleDN: cn=managerrole , dc=dom, dc=ain 
description: Pointy Haired Manager 

There are currently three kinds of complex role: filtered, nested and enumerated roles, with 
corresponding object classes nsFilteredRole, nsNestedRole and nsEnumeratedRole. 

A filtered role specifies an LDAP filter of arbitrary complexity. Entries matching the filter and within 
the sub tree specification are said to possess the role. Here's an example of a filtered role definition: 

dn : cn= buildingl2peopie, dc=dom, dc=ain 
objectclass: top 
objectclass: LDAPsubentry 
objectclass: nsRole 
objectclass: nsComplexRole 
objectclass: nsFilteredRole 
cn: buildingl2people 
nsRoleFilter : building=12 

description: People who work in building 12 

A nested role specifies containment of one or more roles of any type. Here's an example of a nested role 
definition: 

dn: cn=megamanagerrole, dc=dom, dc=ain 
objectclass: top 
objectclass: LDAPsubentry 
objectclass: nsRole 
objectclass: nsComplexRole 
objectclass: nsNestedRole 
cn : megamanaggerrole 

nsRoleDN: cn=managerrole, dc=dom, detain 
nsRoleDN: cn=networkmanager , dc=dom, dc=ain 
description: Super Manager Role within the Company 

An enumerated role is the static group reborn, but with one important difference. No nesting is allowed 
within an enumerated role. This permits a valuable optimization not possible with the DS 1/3/4. x static 
groups. In addition, it is illegal to add a member to an enumerated group where that entry lies outside the 
subtree specification. [Note: I'm not sure we can implement enumerated roles efficiently. Beware that 
DS5.0 may not implement them.] 

dn: cn=peonrole, dc=dom, dc=ain 
objectclass: top 
objectclass: LDAPsubentry 
objectclass: nsRole 
objectclass: nsComplexRole 
objectclass: nsEnumeratedRole 
objectclass: groupof uniquenames 
cn: peonrole 

groupmember : uid=dboreham, ou=people, dc=dom, dc=ain 
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groupmember: uid=merrells, ou=people, dc=dom, dc=ain 
groupmember : uid=claire, ou=people, dc=dom, dc=ain 
description: Lowest of the Low Role within the Company 

Role Operations on the Different Role Types 

A brief description of how to implement each of the five fundamental role operations within each of the 
four role types described above (were possible): 
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Role-Defined Attribute Values 

Covered in detail elsewhere, but an important part of the role story, role-defined attribute values 
(formerly known as Class of Service, also known as Computed Attributes) significantly extend the value 
of roles. Using definitions stored in the DIT, the server is able to generate entry attribute values on-the- 
fly, based on the roles possessed by the entry. Not only is this useful to applications, for example in the 
case of the canonical mailbox quota example, but it's very useful within the server. For example, role- 
defined attributes may be used to control the server's lookthrough limit and size limit on an entry by 
entry basis. 
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For DS5.0, the existing Class of Service mechanism is extended to use an entry's role by simply 
allowing "nsRole" and "nsRoleDN" to be specified as the cos specifier attribute in a cosDefinition entry. 
DS4.1 Class of Service restricted the defining attribute to be single-valued. For DS5.0 role-defined 
attributes, this isn't possible (because nsRole and nsRoleDN can be multivalued). Consequently it 
becomes possible to define COS schemes where the choice of template entry is ambiguous. In order to 
resolve the ambiguity, the template entries may include a priority, in the cosPriority attribute, from the 
new cosTemplate object class. 

dn : cn=messaging_server_cos , cn=cosdef initions , o=NetscapeRoot 
objectclass: top 
objectclass : LDAPsubentry 
objectclass: cosDefinition 

cosTemplateDn : cn-LocalConf ig, cn=MailServerCOS 
cosSpecif ier : nsRoleDN 
cosAttribute : mailboxquota override 
cosAttribute : maysendexternalmail default 



Corresponding example template entries: 

dn: cn="cn=guestnrole, dc=dom, dc=ain", cn=MailServerCOS, cn=LocalConf ig, 

o=NetscapeRoot 

objectclass: top 
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objectclass: cosTemplate 
objectclass: mailserveruser 
cosPriority: 0 
mailboxquota: 10000000 
maysendexternalmail : TRUE 

dn: cn="cn=userrole, dc=dom, detain", cn^MailServerCOS, cn=LocalConf ig, 

o=NetscapeRoot 

objectclass: top 

objectclass: cosTemplate 

objectclass: mailserveruser 

cosPriority: 1 

mailboxquota: 1000000 

maysendexternalmail: FALSE 



Role-Based Access Control 

Access control rules can be defined such that the roles posessed by an entry determine its access rights. 
The aci syntax will be extended to support a "role" property Details to be found in other documents 
[which ones ?]. 

Access Control to Roles 

Because management of managed roles requires access rights to modify the target entries, it becomes 
important to control access appropriately to the nsRoleDN attribute. Access control rules can be defined 
which restrict modification access rights to just the nsRoleDN attribute. Furthermore, access control 
rules can be defined such that a particular client is restricted to adding or removing a specific set of 
values. This means that a particular client will be able to, say, assign and remove access to the 
accounting application (which is done by means of a managed role), but the same client can not promote 
users to the system administrator managed role. 
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What is a Role ? 

DS5.0 Roles embody a new comprehensive entry grouping mechanism, similar to the existing Directory 
Server group concept. Roles address many of the known shortcomings present in static and dynamic 
groups. Roles unify all entry grouping functions within one mechanism that is both easy to use and 
understand. Terminology primer: each role has members, which are the entries said to possess the role. 
In order to achieve reasonable implementation efficiency and to support certain important management 
functions, two different varieties of roles are envisaged. These are termed the simple and complex role 
types. 

How are Roles Defined? 

Each and every role is defined by its own role definition entry. A role is uniquely identified by the 
distinguished name of its defining entry. Role definition entries are LDAP subentries and so inherit the 
subentry mechanism for scope of application to a DIT subtree. LDAP Subentries are defined in 

That each and every role is defined by an entry stored in the DIT is of fundamental importance. Any 
client with appropriate access rights can discover, identify and examine any role definition. Any client 
with appropriate access rights can add a new role definition and modify existing role definitions. Role 
definitions may be replicated in a distributed environment. 

Role Operations 

Given arbitrary roles and entries, the following operations are useful to clients: 

1. Enumerate the members of a role. (Answer the question "which entries have this role ?"). It's also 
useful to be able to resolve this query in a reasonable time (significantly less than the time to find 
the members by brute force examination of all the entries). It's also useful to be able to retrieve the 
entries in a paged or browsing fashion, using the existing LDAP VLV mechanism. 

2. Determine whether a given entry possesses a particular role. It's useful to be able to do this more 
efficiently than by determining all the roles possessed by the entry and then checking whether the 
target role is among that set of roles. 

3. Enumerate all the roles possessed by a given entry. 

4. Assign a particular role to a given entry. 

5. Revoke a particular role from a given entry. 

Tell us about the two Kinds of Role 

Certainly. Imagine that all roles were treated similarly. A role definition could be as complex as required 
or desired. An example of a complex role would be a nested role whose component roles included filters 
using custom matching rules and attribute syntax. Now consider the set of operations we desire to 
support for roles, listed above: 
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1. Membership enumeration: to enumerate the members, a client would need to separately enumerate 
the component roles, by submitting search operations to the server. The results would need to be 
aggregated by the client, eliminating any duplicates. While this is possible, it's onerous. 

2. Determine whether a given entry possesses this role: this is really hard for a client to do. A brute 
force method would be terribly inefficient. Some associative indexing scheme could potentially 
help but seems hard to implement well. 

3. Enumerate all the roles possessed by a given entry: this is harder than (2). 

4. Assign this role to a given entry: This is really hard, requiring semantic knowledge of the role 
definition. 

5. Just as hard as (4). 

So, we have asserted that for a complex role such as the example used above, it is hard or very hard to 
implement any of the five desirable role operations. Therefore we define a role type with deliberately 
limited flexibility, called a simple role, which does allow all five of the desirable role operations to be 
implemented easily and efficiently. Any role that is not a simple role is by definition a complex role. 

A simple role has the following properties: 

1. It's easy and efficient to enumerate its membership. This enumeration can be done using VLV 
controls, allowing better scaling and user experience. 

2. It's easy and efficient to test an entry for possession of a particular role. 

3. It's easy and efficient to enumerate the simple roles a particular entry possesses. 

4. It's obvious by inspection of the role definition how to assign a simple role to a given entry. 

5. It's obvious by inspection of the role definition how to revoke a simple role from a given entry. 

Roles which are not simple are deemed complex, with the implication that one or more (perhaps all) of 
the five operations are hard or very hard. Clients and management agents can easily determine whether a 
given role is of the simple or complex kind, allowing UI to act appropriately. Various server features 
which use roles will not be supported, or supported in a limited or inefficient way, when the target role 
is complex. Internal to the server, it is also possible to deliver notification to subsystems when entries 
move in and out of simple group membership. This can be used to keep metadata cached for 
performance reasons coherent with the DIT contents. 



Roles Compared to Legacy Grouping Mechanisms 
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Role Definitions, Take Two 

Having covered the difference between simple and complex roles, let's return to the details of role 
definition schema: 

There are two "abstract" object classes to distinguish between simple and complex roles: nsSimpleRole 
and nsComplexRole. 

Currently there is only one variety of simple role: the managed role with object class nsManagedRole. 
Membership of a managed role is conferred upon an entry by adding the role's DN to the entry's 
nsRoleDN attrbitute. Example of a managed role definition: 

dn: cn=managerrole, dc=dom, dc=ain 
objectclass: top 
objectclass: LDAPsubentry 
objectclass: nsRole 
objectclass: nsSimpleRole 
objectclass: nsManagedRole 
cn: managgerrole 

description: Manager Role within the Company 
Example of an entry with this role: 

dn: uid^pointyhair , ou=people, dc=dom, dc=ain 

objectclass: top 

objectclass: person 

objectclass: inetorgperson 

uid: pointyhair 

gn: pointy 
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sn: hair 

nsRoleDN: cn=managerrole, dc=dom, dc=ain 
description: Pointy Haired Manager 

There are currently three kinds of complex role: filtered, nested and enumerated roles, with 
corresponding object classes nsFilteredRole, nsNestedRole and nsEnumeratedRole. 

A filtered role specifies an LDAP filter of arbitrary complexity. Entries matching the filter and within 
the sub tree specification are said to possess the role. Here's an example of a filtered role definition: 

dn: cn= buildingl2people, dc=dom, dc=ain 

objectclass: top 

objectclass: LDAPsubentry 

objectclass: nsRole 

objectclass: nsComplexRole 

objectclass : nsFilteredRole 

cn: buildingl2people 

nsRoleFilter : building=12 

description: People who work in building 12 

A nested role specifies containment of one or more roles of any type. Here's an example of a nested role 
definition: 

dn: cn=megamanagerrole, dc=dom, detain 
objectclass: top 
objectclass: LDAPsubentry 
objectclass: nsRole 
objectclass: nsComplexRole 
objectclass: nsNestedRole 
cn: megamanaggerrole 

nsRoleDN: cn=managerrole, dc=dom, dc=ain 
nsRoleDN: cn=networkmanager , dc=dom, dc=ain 
description: Super Manager Role within the Company 

An enumerated role is the static group reborn, but with one important difference. No nesting is allowed 
within an enumerated role. This permits a valuable optimization not possible with the DS1/3/4.X static 
groups. In addition, it is illegal to add a member to an enumerated group where that entry lies outside the 
subtree specification. [Note: I'm not sure we can implement enumerated roles efficiently. Beware that 
DS5.0 may not implement them.] 

dn: cn=peonrole, dc=dom, dc=ain 
objectclass: top 
objectclass: LDAPsubentry 
objectclass: nsRole 
objectclass: nsComplexRole 
objectclass: nsEnumeratedRole 
objectclass: groupof uniquenames 
cn : peonrole 

groupmember: uid=dboreham, ou=people, dc=dom, dc=ain 
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groupmember : uid=merrells , ou=people, dc=dom, dc=ain 
groupmember : uid=claire, ou=people, dc=dom, dc=ain 
description: Lowest of the Low Role within the Company 

Role Operations on the Different Role Types 

A brief description of how to implement each of the five fundamental role operations within each of the 
four role types described above (were possible): 





Managed Role 


Filtered Role 


Nested Role 


Enu 


Membership 
enumeration 


LDAP search with filter 
nsRoleDN=<role's dn> 

(guaranteed to be indexed 
and to suDDort VLV^ 


LDAP subtree search 
with baseDN from 
the 

subtreeSpecification 
and filter from the 
nsRoleFilter attribute. 

(VLV indexing 
optional) 


No generic 
mechanism, 
probably hard. 


Noj 
mec 
hard 


Membership 
Test 


LDAP compare against 
nsRoleDN attribute 


LDAP compare 
against nsRole 
attribute 


LDAP compare 
against nsRole 
attribute 


ld; 

agai 
attri 
com 
agai 
groi 
attib 


Role 

Enumeration 


Read nsRoleDN attribute 


Read nsRole attribute 


Read nsRole 
attribute 


Reai 


Assign Role 


LDAP modify, add role's 
DN to nsRoleDN attribute 


Not meaningful 


Not meaningful 


Add 
thei 
men 


Revoke Role 


LDAP modify, remove 
role's DN from nsRoleDN 
attribute. 


Not meaningful 


Not meaningful 


Rerr 
fron 
men 





Any role 


Simple Role 


Complex Role 


Membership 


No generic 


LDAP search with 


No generic 


enumeration 


mechanism. 


filter 


mechanism, probably 
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nsRoleDN=<role's 
un-^ 


hard. 


Membership Test 


LDAP compare 
operation agamsi 
nsRole attribute 


LDAP compare 
dgdinsi nsivoiei^iN 
attribute 


LDAP compare 
dgdin&i nsivuic 
attribute 


Role Enumeration 


Read nsRole 
duriDUie 


Read nsRoleDN 
diiriDUic 


Read nsRole attribute 


Assign Role 


Not generically 
defined 


LDAP modify, add 
role's DN to 
nsRoleDN attribute 


Not generally 
meaningful 


Revoke Role 


Not generically 
defined 


LDAP modify, 
remove role's DN 
from nsRoleDN 
attribute. 


Not generally 
meaningful 



Role-Defined Attribute Values 

Covered in detail elsewhere, but an important part of the role story, role-defined attribute values 
(formerly known as Class of Service, also known as Computed Attributes) significantly extend the value 
of roles. Using definitions stored in the DIT, the server is able to generate entry attribute values on-the- 
fly, based on the roles possessed by the entry. Not only is this useful to applications, for example in the 
case of the canonical mailbox quota example, but it's very useful within the server. For example, role- 
defined attributes may be used to control the server's lookthrough limit and size limit on an entry by 
entry basis. 
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For DS5.0, the existing Class of Service mechanism is extended to use an entry's role by simply 
allowing "nsRole" and "nsRoleDN" to be specified as the cos specifier attribute in a cosDefinition entry. 
DS4.1 Class of Service restricted the defining attribute to be single-valued. For DS5.0 role-defined 
attributes, this isn't possible (because nsRole and nsRoleDN can be multivalued). Consequently it 
becomes possible to define COS schemes where the choice of template entry is ambiguous. In order to 
resolve the ambiguity, the template entries may include a priority, in the cosPriority attribute, from the 
new cosTemplate object class. 

dn : cn=messaging_server_cos , cn=cosdef init ions , o^NetscapeRoot 
objectclass: top 
objectclass: LDAPsubentry 
objectclass: cosDefinition 

cosTemplateDn : cn=LocalConf ig, cn=MailServerCOS 
cosSpecif ier : nsRoleDN 
cosAttribute : mailboxquota override 
cosAttribute : maysendexternalmail default 

Corresponding example template entries: 



dn: cn="cn=guestnrole, dc=dom, dc=ain", cn=MailServerCOS, cn=LocalConf ig, 

o=NetscapeRoot 

objectclass: top 
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objectclass: cosTemplate 
objectclass: mailserveruser 
cosPriority: 0 
mailboxquota: 10000000 
maysendexternalmail : TRUE 

dn: cn="cn=userrole, dc=dom, dc=ain", cn=MailServerCOS, cn=LocalConf ig, 

o=NetscapeRoot 

objectclass: top 

objectclass: cosTemplate 

objectclass: mailserveruser 

cosPriority: 1 

mailboxquota : 1000000 

maysendexternalmail: FALSE 



Role-Based Access Control 

Access control rules can be defined such that the roles posessed by an entry determine its access rights. 
The aci syntax will be extended to support a "role" property Details to be found in other documents 
[which ones ?]. 

Access Control to Roles 

Because management of managed roles requires access rights to modify the target entries, it becomes 
important to control access appropriately to the nsRoleDN attribute. Access control rules can be defined 
which restrict modification access rights to just the nsRoleDN attribute. Furthermore, access control 
rules can be defined such that a particular client is restricted to adding or removing a specific set of 
values. This means that a particular client will be able to, say, assign and remove access to the 
accounting application (which is done by means of a managed role), but the same client can not promote 
users to the system administrator managed role. 
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